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The  system  defined  file  classes  provided  with  IBM  Simula  are  designed  for  a  batch 
environment  and  there  are  many  obstacles  to  using  these  file  classes  to  create  interactive 
programs  in  the  VM/CMS  environment.  For  example,  it  is  necessary  to  use  DO  names  when 
creating  an  instance  of  a  file  class  and  this  requires  issuing  filedef  commands  before 
program  execution  begins.  When  a  terminal  user  responds  to  a  prompt  by  simply  entering 
<cr>,  this  response  is  interpreted  as  an  end-of-file  and  any  further  attempt  to  read  from  the 
terminal  causes  an  error  termination.  The  error  recovery  provided  by  the  system  defined  file 
classes  is  quite  simple  and  direct:  execution  is  terminated.  In  an  interactive  environment  one 
expects  to  provide  reasonable  opportunities  for  a  user  to  recover  from  minor  errors. 

In  an  interactive  environment  it  is  often  very  useful  to  be  able  to  create  log  files  which 
contain  all  of  the  user's  input  and  to  be  able  to  read  such  files  in  place  of  terminal  input  so 
as  to  recover  from  either  human  errors  or  other  misadventures.  When  such  log  files  are 
being  read  to  recreate  the  state  of  a  program,  it  is  desirable  to  recreate  the  terminal 
transcript  for  the  user  so  that  the  user  is  aware  of  the  state  of  the  program  when  he  is  finally 
in  a  position  to  continue  work  from  the  point  where  he  was  interrupted. 

This  report  describes  two  Simula  classes,  in  file  and  out  file  which  provide  for  dynamic 
file  naming,  error  recovery,  log  file  creation  and  application  as  well  as  character  translation 
for  use  with  apl  terminals. 

The  file  classes  described  here  have  all  of  the  attributes  of  the  system  defined  file 
classes  as  well  as  additional  attributes  that  are  described  here.  It  is  assumed  that  the  reader 
is  familiar  with  the  system  defined  file  classes  and  no  further  documentation  of  the  attributes 
of  these  classes  is  provided. 

These  file  classes  provide  error  recovery  for  both  user  errors  and  for  program  errors. 
There  are  a  number  of  coding  errors  that  may  be  corrected  during  program  execution 
without  changing  the  source  text  and  this  kind  of  error  recovery  requires  some  justification. 
The  cms  Simula  environment  is  basically  the  result  of  grafting  a  batch  processing  run  time 
environment  into  CMS.  As  a  result,  the  only  error  action  taken  by  the  system  is  to  terminate 
execution  and  (optionally)  print  either  a  symbolic  or  hex  dump.  As  a  result,  a  trivial  coding 
error  can  require  another  compilation  of  the  source  program  only  to  detect  another  error. 
The  coding  error  recovery  was  provided  to  improve  the  efficiency  of  program  debugging.  If 
a  symbolic  debugger  were  available,  many  of  these  corrections  would  be  inappropriate 
because  they  could  be  dealt  with  by  the  debugger.  Thus,  this  error  correction  should  be 
viewed  as  a  (hopefully)  temporary  program  development  tool  for  use  until  a  symbolic 
debugger  is  available. 

Section  i  describes  the  use  of  class  injile  and  Section  2  describes  the  use  of  class 
out  file  by  means  of  examples.  Section  3  provides  instructions  for  using  these  file  classes 
on  the  Virginia  Tech  vm/cms  system.  A  listing  of  the  source  text  of  these  the  code  that  is 
added  to  a  user  program  appears  as  an  appendix. 

The  following  conventions  are  used  in  this  report.  When  a  sketch  of  program  text 
appears,  this  text  is  printed  in  Algol  publication  format,  i.e.,  boldface  keywords,  italic 
identifiers  and  italic  Edit  Case  tor  system  defined  identifiers.  The  reader  should  assume  that 
this  is  an  example  that  was  constructed  to  explain  a  particular  concept  rather  than  an 
excerpt  from  a  specific  program.  When  an  extract  of  an  actual  program  occurs  in  the 
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document,  it  is  printed  in  a  fixed  pitch  font  with  upper  case  keywords,  Edit  Case  system 
defined  identifiers  and  lower  case  user  defined  identifiers.  System  commands  and  input  text 
to  be  typed  by  a  user  also  appear  in  a  fixed  pitch  font. 


1.  Input  Files. 

Just  as  for  the  system  defined  class  Infile,  the  first  step  in  reading  a  file  is  to  create  an 

instance  of  a  file  object.  This  might  be  done  as  follows: 

ret(injile)  input; 

input  new  inJileK file  spec»; 

In  this  code  fragment,  <file  spec>  is  a  CMS  file  id  or  the  string  tty :  in  any  mixture  of  upper 
and  lower  case  letters.  If  a  portion  of  the  file  id  is  missing,  it  is  provided  in  accord  with  the 
defaults  described  below.  When  this  statement  is  executed,  the  value  of  input  is  a  closed  file 
object  whose  input  will  be  received  from  the  device  specified  by  <file  spec>. 

If  the  actual  parameter  of  injile  is  the  text  object  TTY:,  then  input  is  read  from  the 
terminal.  Note  that  the  text  objects  tty:.  tTy:  and  so  forth  are  equivalent  in  this  context. 
If  the  actual  parameter  is  a  text  object  other  than  one  of  these  strings,  then  the  actual 

parameter  is  interpreted  as  a  (partially  specified)  cms  file  id. 

Recall  that  a  file  id  is  a  string  of  the  form  <fn>[  <ft>[  <fm>]].  If  the  <ft>  is  omitted,  the 
<ft>  data  will  be  used.  If  <fm>  is  omitted,  all  accessable  disks  will  be  searched  in  accord 
with  the  search  list  specified  by  the  profile.  The  first  file  in  this  search  that  matches  <fn>  <ft> 
will  be  selected.  If  there  is  no  such  file,  a  message  will  be  printed  on  the  terminal  and  the 
user  will  be  asked  to  specify  another  file  id.  By  replying  to  this  request  for  a  new  file  id  with 
the  string  CMS : .  the  user  may  enter  cms  subset  to  examine  his  directory  to  select  an  input 
file.  To  return  to  the  running  program,  the  user  enters  the  string  RETURN  (in  any  mixture  of 
upper  and  lower  case  letters) 

A  program  segment  to  read  a  file  id  from  the  terminal  and  then  create  an  injile  might 
be  the  following: 

REF (in  file)  i nput : 

TEXT  f 7 1 e_ i d • 

Outtext( "F i leid.  "): 

Breakout  image : 

In  image : 

file_id  :-  Copy ( Image . Str  ip ) : 

input  :-  NEW  i n_f i 1 e ( f i  1  e_id ) : 

and  the  terminal  transcript  would  look  like  this  (assuming  that  the  file  mumble  foo  does  not 
exist). 


F  i  leid:  mumb 1 e  foo 
?  File  MUMBLE  FOO  does  not  exist. 

Enter  file  id:  /CMS:/ 

At  this  point,  the  user  could  enter  cms  subset  and  look  around  to  select  the  appropriate  file. 
When  this  is  completed,  the  user  enters  RETURN  and  the  dialog  continues  as  follows 


Simula  File  Classes 


(assuming  that  the  actual  input  file  is  alpha  Simula): 

#  return 

[Returning  to  SIMULA  program  execution.] 

Enter  file  id:  /CMS:/:  alpha  Simula 

After  this,  the  value  of  input  is  a  closed  input  file  object  connected  to  file  alpha  Simula. 
Observe  that  the  prompt  character  Is  #  when  cms  subset  is  being  used. 

Instances  of  class  injile  are  opened  in  the  same  way  that  instances  of  the  system 
defined  class  infile  are  opened,  i.e.,  to  open  the  injile  object  input,  the  statement 

input. Open (Blanks (80) ) 

is  executed.  There  is,  however  much  more  run  time  error  recovery  when  the  Open  attribute 
of  injile  is  used.  The  following  error  recovery  is  provided: 

(1)  If  the  file  object  associated  with  input  is  already  open,  then  an  error 
message  is  printed  on  the  terminal  and  the  user  is  given  the  option  of 
continuing  execution  or  terminating  execution.  The  text  of  the  message 
is: 

?  in_f  i le.Open :  File  ALPHA  SIMULA  is  already  open. 

Do  you  want  to  continue  reading  the  file?  /y/: 

If  the  user  responds  with  a  carriage  return,  execution  continues  as  if  the 
file  were  closed  when  open  was  called.  However,  if  records  have  already 
been  read  from  the  file,  reading  continues  from  the  next  record:  the  file  is 
not  rewound. 

(2)  If  the  record  length  of  the  file  is  greater  than  the  length  of  the  actual 
parameter  to  the  file  object,  the  user  is  given  the  option  of  extending  the 
image  attribute  of  the  file  object  or  terminating  execution.  For  example,  if 
the  above  call  on  Open  were  executed  and  if  the  record  length  of  file 
alpha  Simula  is  132,  the  following  terminal  transcript  would  occur: 

?  in_f i le. Open :  File  ALPHA  SIMULA  has  a  record  length  greater 
than  the  length  of  the  provided  buffer. 

Do  you  want  to  extend  the  buffer?  /y / : 

If  the  user  answers  yes  by  entering  a  return,  then  input. image  is  extended 
to  Blanks!  132)  and  if  the  user  answers  no,  then  execution  is  terminated. 

Class  injile  has  the  usual  attributes  Setpos.  Pos,  More.  Length.  Close,  inimage. 
Lastitem,  intext.  inint.  mfrac.  inreai  and  inchar  of  the  system  defined  class  infile  but  these 
attributes  of  the  class  provide  for  error  recovery.  In  the  system  defined  class,  it  is  a  run  time 
error  to  call  one  of  these  procedures  when  the  file  associated  with  the  object  is  closed. 
When  class  injile  is  used,  an  attempt  to  read  from  a  closed  file  results  in  an  error  message 
and  the  user  may  decide  to  open  the  file  or  terminate  execution.  For  example,  if  input. inmt 
were  called  while  file  alpha  Simula  is  closed,  the  following  dialog  would  occur: 

%  in_fi le. Inint:  File  ALPHA  SIMULA  Is  closed. 

Oo  you  want  to  open  this  file?  /y/: 
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If  the  user  answers  with  a  return  or  yes,  then  the  file  is  opened  and  the  first  record  is  read  to 
satisfy  the  call  to  inint  and  if  the  user  answers  no  then  execution  is  terminated  after  an 
optional  symbolic  dump. 

The  attribute  Close  of  injile  behaves  in  the  same  way  as  the  system  defined  attribute  of 
infile  except  that  a  call  to  Close  will  not  cause  a  termination  of  execution  if  the  file 
associated  with  the  object  is  already  closed.  Instead,  the  following  advisory  messages  are 
printed  on  the  terminal: 

[X  in_fi le. Close:  Fite  ALPHA  SIMULA  is  already  closed.] 

[Execution  continues.] 

The  attribute  Endfile  of  class  in_fiie  behave  in  exactly  the  same  way  as  the 
corresponding  attribute  of  the  system  defined  class  Infile. 

Instances  of  class  injile  have  additional  attributes  that  are  not  possesed  by  instances  of 
the  system  defined  class  infile.  Each  of  these  attributes  is  described  below.  The  attributes 
are  described  by  exhibiting  the  declaration  of  the  attribute  followed  by  a  description  of  the 
attribute. 

boolean  procedure  Opened 

This  procedure  returns  the  value  true  when  the  file  associated  with  the  instance  of 
class  injile  is  open  and  false  otherwise.  This  attribute  duplicates  an  attribute  of  the  file 
classes  in  D£C-10  Simula  It  is  sometimes  convenient  to  use  this  attribute  when  one  wishes 
to  take  a  different  course  of  action  depending  on  the  state  of  the  file. 

text  procedure  fiie_spec 

The  return  value  of  this  procedure  is  a  text  object  whose  value  is  the  cms  file  id  of  the 
file  associated  with  the  instance  of  class  injile.  The  text  object  is  in  the  same  format  as  the 
output  of  the  cms  command  list.  That  is.  the  file  name  and  file  type  each  occupy  eight 
spaces  (possibly  padded  with  blanks  on  the  right)  and  the  file  mode  occupies  two  spaces. 
There  is  a  single  space  between  the  file  name  (padded  to  eight  spaces)  and  the  file  type  and 
another  space  between  the  file  type  (padded  to  eight  spaces)  and  the  file  mode. 

boolean  echo 

This  attribute  of  an  inj<:e  is  meaningful  only  if  the  file  associated  with  the  instance  of 
the  class  is  a  disk  file  When  the  file  is  a  disk  file,  the  value  of  echo  controls  the  behavior  of 
the  file  obiect  as  follows  (i)  if  echo  has  the  value  true,  then  characters  read  from  the  file 
are  copied  onto  the  terminal  as  they  are  being  read  from  the  disk.  (2)  If  echo  has  the  value 
false  then  this  echoing  is  not  performed. 

This  attribute  of  class  injile  was  included  to  make  it  possible  to  read  files  which  contain 
user  input  that  was  typed  during  a  previous  execution  of  the  program  and  then  reproduce 
the  terminal  transcript  in  the  continuation  session.  The  echo  attribute  combined  with  the  log 
attribute  described  below  makes  it  very  easy  to  write  code  to  function  in  this  way.  See  the 
example  below. 

t*Vcut_fHel  log 

if  the  value  of  this  aitribut  of  an  injile  is  set  to  none,  then  the  class  instance  behaves 
lust  as  one  would  expect  However,  the  following  occurs  if  log  is  different  from  none: 


/T- 
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Each  line  of  input  from  the  input  file  (or  terminal)  is  written  to  the  file  associated  with  the 
value  of  log.  Note  that  only  the  input  received  from  the  device  is  written  to  this  file; 
program  output  is  not  recorded. 

boolean  divert 

The  value  of  this  attribute  controls  the  action  of  class  injile  when  an  end-of-file  is 
encountered  in  a  disk  file.  If  the  value  of  divert  is  false,  then  the  instance  of  class  injile 
behaves  as  usual  upon  reaching  the  end  of  file.  On  the  other  hand,  if  divert  is  true,  then 
and  end-of-file  from  the  disk  is  used  to  transfer  the  source  of  input  from  the  disk  file  to  the 
terminal.  For  example,  suppose  that  a  program  is  reading  file  alpha  Simula  and  that  the  end- 
of-file  is  encountered  while  divert  is  true.  The  terminal  transcript  would  look  like  this: 

[%  in_f i le . Inimage :  Input  from  file  ALPHA  SIMULA  diverted  to 
TTY: .] 

After  this,  additional  reads  from  the  file  (including  the  read  which  initiated  the  end-of-file)  are 
satisfied  by  reads  from  the  terminal.  This  attribute  is  particularly  useful  when  reading  log 
files  generated  with  the  help  of  the  log  attribute  described  above. 

Example 

The  following  code  fragment  illustrates  the  use  of  class  injile  to  create  an  input  file 
which  uses  the  echoing  and  logging  facilities  described  above. 

rel(injile)  input: 
reUoutJ/le)  logjile; 

Ouffexf("Input  file:  "): 

Breakoutimage: 

input  :■  new  injile(lmage.strip): 

OuttextC'Loq  file:  "): 

Breakoutimage: 

lmmage: 

logjile  .--  new  outJile(lmage.Strip): 

mpul. echo  :  x  true: 
input. divert :  *  true. 
input. log  :■  logjile: 


In  the  first  sequence  of  executable  statements,  an  injile  and  an  outjile  are  created  using 
files  specified  by  the  user  from  the  terminal  In  the  second  group  of  executable  statements, 
the  echo,  divert  and  log  attributes  of  input  are  initialized.  The  files  must,  of  course,  be 
opened  befor  reading  and  writing  begins. 


When  this  program  is  executed,  the  user  is  first  asked  to  specify  the  input  file  from 
which  data  is  to  be  read.  If  there  is  no  existing  log  file,  then  the  appropriate  response  would 
be  the  string  tty:  to  cause  all  input  to  be  read  directly  from  the  terminal.  The  file  id  that  is 
the  response  to  the  prompt  Log  file:  becomes  the  file  id  of  a  file  that  contains  all  input 
that  was  entered  from  the  terminal  in  response  to  calls  to  input.lnimage.  At  some  point  in 
program  execution,  it  might  be  desirable  to  suspend  execution  of  the  program.  This  can  be 
accomplished  by  entering  control-C  (tC)  in  response  to  a  request  for  input.  Suppose  that 
the  log  file  that  was  created  during  this  execution  was  file  alphai  log. 
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The  next  time  the  program  is  executed,  the  user  could  answer  ALPHA  1  LOG  to  the 
prompt  Input  file:.  The  response  to  the  prompt  for  a  log  file  might  be  ALPHA2  LOG. 
During  this  execution  of  the  program,  all  of  the  responses  from  the  first  execution  will  be 
read  from  file  alphai  log  and  both  these  responses  and  program  output  would  be  printed  on 
the  terminal.  When  the  end  of  file  alphai  log  is  encountered,  a  message  will  be  written  on 
the  terminal  and  additional  inputs  will  be  read  from  the  terminal.  At  the  end  of  this  program 
execution,  file  alpha2  log  will  contain  all  of  the  user  responses  from  the  first  and  second 
execution  of  the  program.  This  file  could  then  be  used  to  bring  the  program  back  to  its  state 
at  t.  e  end  of  the  second  execution.  After  this,  execution  could  continue  as  though  the 
entire  computation  had  been  done  in  one  session. 

Using  log  files  provides  a  certain  amount  of  security  agains  accidential  loss  of  important 
results  and  provides  a  rather  limited  replacement  for  a  checkpoint  facility  (which  is  not 
available  in  cms). 

Useful  Details 

The  usual  cms  convention  is  that  an  empty  line  from  the  terminal  is  an  end-of-file  for  the 
terminal.  This  convention  proves  to  be  quite  inconveneint  in  an  interactive  environmnet. 
When  using  class  inJUe.  the  following  conventions  apply: 

(1)  An  empty  line,  i.e..  responding  to  a  request  for  input  by  simply  hitting  the 
return  key.  is  read  as  an  empty  line  consisting  of  image. Length  blanks. 

(2)  A  line  consisting  of  control-Z  (tZ)  followed  by  return  is  read  as  an  end-of- 
file  from  the  terminal. 

(3)  A  line  consisting  of  control-C  (tC)  followed  by  return  is  read  as  a  request 
to  terminate  execution.  Execution  is  terminated  and  all  open  files  are 
closed. 

Note  that  in  (2)  and  (3)  the  input  line  must  consist  of  the  control  character  immediately 
followed  by  return.  A  control  character  followed  by  a  blank  and  then  a  return  will  NOT  be 
interpreted  in  this  way  --  it  will  be  transmitted  to  the  program. 

This  set  of  typing  conventions  was  implemented  to  provide  a  more  reasonable  terminal 
interface  for  cms  Simula.  It  is  still  not  a  satisfactory  solution  to  the  problem  of  providing  a 
comfortable  interactive  environment  but  it  is  substantially  more  convenient  than  the  version 
provided  by  the  system. 


2.  Output  Files. 

Just  as  for  the  system  defined  class  Outfile.  the  first  step  in  writing  a  file  is  to  create  an 

instance  of  a  file  object.  This  might  be  done  as  follows: 

reUoutJUe)  output: 

output  .-  new  ouf_f//e(<file  spec>j; 

Just  as  for  an  input  file  object,  in  this  code  fragment  <file  spec>  is  a  cms  file  id  or  the  string 

tty :  in  any  mixture  of  upper  and  lower  case  letters.  If  a  portion  of  the  file  id  is  missing,  it  is 

provided  in  accord  with  the  defaults  described  below.  When  this  statement  is  executed,  the 
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value  of  output  is  a  closed  file  object  whose  output  will  be  directed  to  the  device  specified 
by  <file  spec>.  [An  obscure  detail  possibly  of  interest  to  hackers:  A  filedef  for  the  output  file 
is  not  executed  during  the  creation  of  an  outjile  because  the  record  length  of  the  file  is 
unknown  until  the  call  to  Open  which  must  occur  before  data  transmission.] 

If  the  actual  parameter  of  outjile  is  the  text  object  TTY : ,  then  output  is  written  to  the 
terminal.  Note  that  the  text  objects  tty:,  tTy:  and  so  forth  are  equivalent  in  this  context. 
If  the  actual  parameter  is  a  text  object  other  than  one  of  theses  strings,  then  the  actual 
parameter  is  interpreted  as  a  (partially  specified)  cms  file  id. 

Recall  that  a  file  id  is  a  string  of  the  form  <fn>[  <ft>[  <fm>]].  If  the  <ft>  is  omitted,  the 
<ft>  log  will  be  used.  If  <fm>  is  omitted,  then  the  mode  will  be  determined  by  examining  all 
accessable  disks  in  the  search  list  specified  by  the  profile.  The  file  mode  will  be  the  mode  of 
the  first  disk  in  this  sequence  with  the  property  that  the  user  has  write  access  to  the  file.  In 
most  applications,  this  will  be  the  A(191)  disk.  If  the  user  does  not  have  write  access  to  any 
disk,  a  non-recoverable  error  will  occur  at  the  first  attempt  to  transfer  data  to  the  file. 

A  program  segment  to  read  a  filed  id  from  the  terminal  and  then  create  an  outjile  might 
be  the  following: 

REF(out_f i le)  output: 

TEXT  f i 1 e _ i d : 

Outtext( "Output  file:  "); 

Breakoutimage: 

file_id  Copy (Sys in . Image . Str ip) : 

output  NEW  out_f i 1e(f i le_id) : 

and  the  terminal  transcript  would  look  like  this: 

Output  file:  fumble  foo 

After  this,  the  value  of  output  is  a  closed  file  object  that  will  write  output  to  disk  file 
fumble  foo.  The  next  step  is  to  open  the  file  with  the  procedure  call: 

output. Open (8 lanks( 132) ) 

Executing  this  call  will  open  the  file  named  in  the  creation  of  output  (fumble  foo  in  this 
case)  to  be  written  as  a  fixed  length  record  file  with  a  record  length  of  132  characters.  As  in 
the  system  defined  class  Outfile,  the  length  of  the  parameter  of  Open  determines  the  record 
length  of  the  file  to  be  written. 

The  system  defined  class  Outfile  will  terminate  execution  if  the  file  is  open  when  a  call 
to  Open  is  executed.  The  Open  attribute  of  an  outjile  will  give  the  user  the  option  of 
continuing  execution  in  this  case.  The  terminal  transcript  lookis  like  this: 

?  out_f i 1 e . Open :  File  FUMBLE  FOO  is  already  open. 

Oo  you  want  to  continue  writing  the  file?  /y/: 

If  the  user  selects  the  answer  "yes"  by  hitting  the  return  key,  then  data  transmission  to  the 
file  continues.  On  the  other  hand,  if  the  user  responds  with  the  character  n  (in  upper  or 
lower  case),  execution  will  be  terminated.  If  the  user  elects  to  continue  program  execution, 
additional  outputs  written  to  the  file  will  be  appended  to  the  data  already  written  to  the  file. 
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Class  outjile  has  the  usual  attributes  Setpos,  Pos,  More,  Length,  Outchar,  Outint, 
Outrac,  Outreal,  Outfix  and  Outimage  of  class  Outfile.  However,  there  is  provision  for  error 
recovery  if  there  is  an  attempt  to  execute  one  of  these  procedures  when  the  file  is  closed. 
Here  is  an  example  of  the  terminal  dialog: 

%  out_file. Setpos:  File  FUMBLE  F00  is  closed. 

Do  you  want  to  open  this  file?  /y/: 

If  th-;  user  answers  this  query  affirmatively,  then  the  program  will  request  the  record  length 
of  the  output  file  as  follows: 

Enter  length  of  output  lines:  /80/: 

The  response  to  this  prompt  may  be  any  positive  integer  less  than  256  (a  vm  imposed 
limitation).  The  file  associated  with  the  file  object  will  be  opened  to  write  with  the  specified 
record  length.  Note  that  this  will  cause  the  destruction  of  data  that  is  already  in  the  file! 

The  attribute  Outtext  of  class  outjile  performs  in  the  same  way  as  the  system  defined 
version  but  it  has  two  error  correcting  capabilities.  As  for  all  of  the  other  attributres  of  the 
class,  it  is  possible  to  recover  from  an  attempt  to  write  on  a  closed  file.  The  second 
extension  provides  for  recovery  from  a  fairly  common  error.  In  the  system  defined  version.  If 
Outtext  is  called  to  write  a  text  object  consisting  of,  say,  25  characters  and  there  is  only 
space  for  24  characters  in  Image,  then  an  error  termination  will  occur.  In  the  version 
described  here,  the  first  24  characters  of  the  argument  to  Outtext  will  be  added  to  image 
and  then  a  call  to  Outimage  is  executed.  After  this  call,  the  remaining  character  in  the 
parameter  of  Cuftexf  is  placed  into  Image.  More  generally,  a  text  object  of  any  length  can 
be  transmitted  to  an  output  file  with  a  single  call  to  Outtext.  The  text  object  will  be  written  to 
the  file  using  as  many  lines  as  are  needed  to  contain  the  text  value.  If  less  than  a  full  line  of 
characters  remain  after  lines  are  written,  these  characters  remain  in  Image  and  image.  Pos 
has  the  appropriate  value. 

The  attribute  Close  of  class  outjiie  provides  for  error  recovery  if  the  procedure  is  called 
when  the  file  is  already  closed  Here  is  an  example  of  the  message  that  is  printed  on  the 
terminal  when  this  occurs: 

[7c  out_f  i  1  e  .  C 1  ose  :  File  FUMBLE  F00  is  already  closed.] 

[Execution  continues.] 

Class  outjile  has  a  number  of  additional  attributes  that  provide  for  printing  prompts  and 
reading  a  response  on  the  same  line,  for  echoing  output  to  a  disk  file  onto  the  terminal  and 
for  performing  translation  so  that  output  can  be  written  to  apl  terminals  while  preserving  the 
characters  in  the  text.  These  attributes  are  described  by  exhibiting  the  declaration  of  the 
attribute  followed  by  a  description  of  the  attribute. 

procedure  Breakoutimage 

When  the  procedure  Outimage  is  called  to  write  a  record  to  a  disk  file,  the  value  of  the 
image  attribute  (including  trailing  blanks)  is  written  to  the  file.  In  contrast,  when  Outimage  is 
called  to  write  a  record  to  the  terminal,  the  value  of  image. Strip  followed  by  <cr><lf>  is 
written  to  the  terminal.  This  means  that  the  next  piece  of  input  or  output  will  appear  on  the 
next  line.  In  many  interactive  applications,  it  is  convenient  to  be  able  to  transmit  characters 
to  the  terminal  without  a  trailing  <crXlf>.  In  dec-io  Simula,  the  attribute  Breakoutimage  cf 
class  Outhle  provides  this  capability.  The  corresponding  attribute  of  class  outjile  has  the 
same  property  for  ibm  Simula. 
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The  Breakoutimage  attribute  of  an  outjile  may  be  described  as  follows:  If  the  instance 
of  outjile  is  associated  with  the  terminal,  then  image. Subd, image. Pos)  is  written  to  the 
terminal  without  a  trailing  <cr><lf>.  If  the  instance  of  outjile  is  associated  with  a  disk  file, 
then  Breakoutimage  is  equivalent  to  Outimage. 

Some  examples  might  illustrate  an  application  of  Breakoutimage.  Suppose  the  program 
fragment: 


Outtext( "Enter  your  name:  "): 

Outimage ; 

Inimage 

is  executed.  The  terminal  transcript  might  look  like  this: 

Enter  your  name: 

Bill  Jones 

Notice  that  the  prompt  and  response  are  on  different  lines.  On  the  other  hand,  if  the 
program  fragment: 

Outtext( "Enter  your  name:  "): 

Breakoutimage : 

Inimage 

were  executed,  the  terminal  transcript  would  look  like  this: 

Enter  your  name:  Bill  Jones 

boolean  procedure  Opened 

This  procedure  returns  the  value  true  if  the  file  associated  with  the  file  object  is  open 
and  false  otherwise.  This  attribute  of  class  outjile  corresponds  to  the  attribute  of  class 
Outfite  m  oEC-io  Simula  with  the  same  name.  This  attribute  makes  it  easier  to  write 
programs  that  take  different  courses  of  action  depending  on  the  state  of  a  particular  file 

text  procedure  file_spec 

The  return  value  of  this  procedure  is  a  text  object  whose  value  is  the  cms  file  id  of  the 
file  associated  with  the  instance  of  class  outjile-  The  text  object  is  in  the  same  format  as 
the  output  of  the  cms  command  list.  That  is.  the  file  name  and  file  type  each  occupy  eight 
spaces  (possibly  padded  with  blanks  on  the  right)  and  the  file  mode  occupies  two  spaces. 
There  is  a  single  space  between  the  file  name  (padded  to  eight  spaces)  and  the  file  type  and 
another  space  between  the  file  type  (padded  to  eight  spaces)  and  the  file  mode 

boolean  echo 

The  attribute  echo  is  only  meaningful  if  the  instance  of  class  outjile  is  associated  with  a 
disk  file.  In  this  case,  if  echo  has  the  value  true,  then  all  lines  written  to  the  file  are  also 
written  to  the  terminal.  If  echo  is  false,  then  this  echoing  to  the  terminal  is  not  performed. 
If  the  instance  of  outjile  is  associated  with  the  terminal,  the  value  of  echo  is  ignored. 

apl  Character  Set  Support 

ascii/ apl  terminals  have  the  property  that  they  can  display  characters  in  either  the  ascii 
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or  apl  character  sets.  Most  modern  ascii/apl  terminals  also  have  the  property  that  the 
character  set  can  be  changed  under  the  control  of  the  host  computer  to  which  the  terminal 
is  conneced.  This  second  character  set  on  a  terminal  provides  a  number  of  exciting 
possibilities  for  the  use  of  terminals  but  it  also  imposes  some  additional  work  on  the 
programmer. 

For  example,  if  a  program  writes  an  ascii  string  to  the  terminal  when  the  terminal  is  in 
the  apl  character  set.  it  is  quite  likely  that  the  text  printed  on  the  terminal  will  be 
uni'-  elligible  to  the  user.  A  similar  situation  arises  if  a  string  of  characters  in  the  apl 
character  set  is  sent  to  the  terminal  when  the  terminal  is  in  the  ascii  character  set.  Thus,  it 
is  the  responsibility  of  the  programmer  to  keep  track  of  the  character  set  state  of  the 
terminal  and  to  take  appropriate  action. 

The  use  of  ascii/apl  terminals  is  further  complicated  by  the  fact  that  there  are  two 
generally  accepted  mappings  of  apl  characters  onto  ascii  characters.  This  unfortunate  state 
of  affairs  is  a  result  of  posponing  a  decision  concerning  a  standard  for  this  mapping  until 
terminal  manufactures  were  committed  to  both  character  mappings.  The  two  mappings  of 
apl  characters  onto  ascii  characters  are  called  key-paired  and  bit-paired. 

Class  outjile  has  six  procedure  attributes  that  make  it  easier  to  work  with  ascii/apl 
terminals.  These  include  procedures  to  change  between  the  three  character  sets  (ascii,  key- 
paired  apl  and  bit-paired  apl)  and  to  determine  the  state  of  the  terminal  character  set.  In 
addition,  there  are  procedures  to  write  ou'put  while  bypassing  the  character  set  control  and 
translation  mechanisms 

By  definition,  character  set  0  is  the  ascii  character  set.  character  set  1  is  key-paired  apl 
and  character  set  2  is  bit-paired  apl 

integer  procedure  termjyce 

The  return  value  of  this  procedure  is  the  character  set  number  of  the  current  terminal 
character  set.  When  the  return  value  of  termjype  is  0.  text  written  to  the  terminal  or  a  disk 
file  is  transmitted  without  translation. 

When  the  return  value  of  termjype  is  1  then  all  output  transmitted  to  the  terminal  or 

disk  file  by  way  of  calls  to  Ouumage  or  Breakoutimage  is  translated  to  preserve  the 

appearance  of  the  text  object  when  it  is  printed  on  a  key-paired  ascii/apl  terminal.  This 
translation  converts  lower  case  letters  into  the  (upper  case)  apl  letter  and  converts  upper 
case  letters  into  underscored  apl  letters.  The  graphics  are  translated  subject  to  preserving 
the  appearance  or  function  of  the  character. 

When  the  return  value  of  termjype  is  2  then  all  output  transmitted  to  the  terminal  or 

disK  file  by  way  of  calls  to  Outimage  or  Breakoutimage  is  translated  to  preserve  the 

appearance  of  the  text  object  when  it  is  printed  on  a  bit-paired  ascii/apl  terminal.  The 
translation  is  as  described  above. 


When  an  instance  of  outjile  is  created,  the  defalut  terminal  character  set  is  0  and  this 
will  be  the  return  value  of  ferm_type. 

procedure  set_ascii 

When  this  procedure  is  called,  the  character  set  associated  with  the  file  is  changed  to 
ascii.  If  the  character  set  was  different  from  ascii  and  if  there  were  characters  in  image. 
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then  these  characters  are  emitted  in  the  previous  character  set.  Characters  to  change  the 
character  set  of  the  terminal  are  sent  to  the  terminal  or  file. 

procedure  set_key_paired  I 

When  this  procedure  is  called,  the  character  set  associated  with  the  file  is  changed  to 
key-paired  apl.  The  same  character  set  change  and  buffer  emptying  described  above  is 
performed. 

procedure  set_bit _ paired 

When  this  procedure  is  called,  the  character  set  associated  with  the  file  is  changed  to 
bit-paired  apl.  The  character  set  change  characters  and  buffer  emptying  procedure  is 
similar  to  the  procedure  described  for  setjascii.  I 

procedure  apl_outimage  ' 

This  procedure  is  the  same  as  Outimage  except  that  character  translation  as  described 
above  is  not  performed  independent  of  the  state  of  the  terminal,  disk  file  and  character  set. 

i 

procedure  api_breakoutimage 

This  procedure  is  the  same  as  Breakoutimage  except  that  character  translation  as 
described  above  is  not  performed  independent  of  the  state  of  the  terminal,  disk  file  and  t 

character  set.  i 


3.  Directions  for  Using  these  File  Classes 

The  file  classes  described  here  are  implemented  as  declared  classes  which  also  make 
calls  on  procedures  that  are  contained  in  libsim.  This  section  provides  directions  for 
incorporating  these  file  classes  into  programs  and  a  sketch  of  their  implementation. 


The  files  that  support  the  file  classes  described  here  are  stored  on  the  1 91  disk  of  cms 
userid  csdulles.  If  you  are  going  to  use  these  file  classes,  it's  a  good  idea  to  add  the 
following  three  lines  to  your  profile  exec: 

cp  link  csdulles  191  330  rr  all 

access  330  D/a 

global  txtlib  libsim  simlib 

In  any  case,  these  three  commands  must  be  executed  before  you  attempt  to  compile  or 
execute  a  program  that  uses  these  file  classes. 

A  program  that  uses  these  file  classes  must  be  compiled  using  the  sim  exec  that  is 
provided  on  csdulles.  Suppose  that  a  program  that  uses  these  file  classes  is  in  file  alpha 


Simula.  This  program  would  be  compiled,  loaded  and  executed  by  entering  the  cms 
command: 

sim  alpha 

When  a  program  is  compiled  in  this  way.  the  usual  default  value  of  the  compiler  parameters 
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are  used.  The  output  from  the  compiler  (a  text  file)  is  loaded  and  then  a  module  file  is 
written  to  the  disk.  After  the  module  is  written,  execution  of  the  program  begins.  [It  takes 
the  loader  a  terribly  long  time  to  load  Simula  programs  and  it  is  possible  to  save  a  great  deal 
of  time  by  creating  module  files.].  When  this  exec  is  invoked  to  compile  a  program,  it  will 
delete  an  existing  module  file  with  the  same  name. 

It  is  necessary  to  make  a  few  minor  changes  in  a  source  program  that  uses  these  file 
classes.  Suppose  that  the  text  of  an  ordinary  Simula  program  consists  of  begin  ...  end. 
This  program  would  be  modified  as  follows: 

%C0PY  PREFIX 
BEGIN 


ENO; 

%C0PY  POSTFIX 

The  effect  of  this  is  to  incorporate  the  declarations  of  the  classes  injile  and  outjile  into  the 
program.  In  addition.  Sysin  is  declared  and  opened  as  an  injile  and  Sysout  is  declared  and 
opened  as  an  outjile.  Observe  that  the  end  that  terminates  the  program  must  be  follwed  by 
a  sem-colon. 

If  you  are  interested  in  exploring  the  details  of  the  code  introduced  into  your  program  by 
this  change,  you  might  want  to  consult  the  listings  of  files  prefix  Simula  and  postfix  Simula 
which  appear  in  the  appendix.  These  files  are  added  to  your  program  by  the  two  “icopv 
commands  to  the  compiler. 
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Appendix 

Listing  of  Source  Code 


The  source  code  contained  in  files  prefix  Simula  and  postfix  Simula  is 
shown  on  the  following  pages.  This  is  a  reproduction  of  the  actual  files 
as  printed  on  a  Diablo  terminal  using  the  utility  program  ttyspl. 


EXTERNAL  ASSEMBLY  PROCEDURE  wplsave. 
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